API

获取

参数
- id (integer) - 玩家ID
返回
- player (player) - 玩家

local player = base.player(id)

add

增加属性

参数
- state (string) - 属性名称
- value (number) - 数值

玩家属性说明见这里

player:add('金钱', 100)

controller

获取玩家控制者

返回
- controller (string) - 会是以下值中的一个
  - human - 用户
  - none - 空位
  - computer - 电脑
  - ai - AI
  - human-ai - 像人AI

local controller = player:controller()

create_item

创建物品

参数
- name (string) - 物品名
- target (point/unit) - 创建位置
返回
- item (item)

创建出来的物品所有者为player。当target为点，物品会创建在地上；当target为单位，物品会创建在单位身上，但如果该单位的[物品栏]已满则会创建在单位所在的位置上。

local item = player:create_item('物品名', point)
local item = player:create_item('物品名', unit)

create_unit

创建单位

参数
- name (string/unit) - 单位名字/要复制的单位
- where (point) - 创建位置
- face (number) - 面朝方向
- on_init (function) - 初始化函数
返回
- unit (unit) - 单位

创建出来的单位由player控制。如果name是一个字符串，那么会创建名称为name的单位。如果name是一个单位，那么会复制该单位，目前该行为等同于create_illusion。单位创建后会最先执行on_init，你可以在这里给单位初始化一些数据。创建单位的流程如下：

执行on_init
触发单位-初始化事件
添加技能
触发[单位-创建]事件

local unit = player:create_unit('$$td_template_ts_template_1_xevb.unit.狼人.root', where, face, function (unit)
    -- 对unit进行初始化设置
end)

注意创建单位后在当帧立即在客户端使用该单位的信息可能有问题，详见单位-初始化中的描述

each_player

遍历玩家

参数
- type (string) - 玩家类型
返回
- player (player) - 玩家

当设置了type后，会遍历所有该类型的玩家（根据config中的玩家定义）；否则会遍历所有玩家。按照玩家ID从小到大的顺序遍历。

for player in base.each_player 'user' do
    -- 你的代码
end

event

注册事件

参数
- name (string) - 事件名
- callback (function) - 事件函数
返回
- trigger (trigger) - 触发器
事件参数
- trigger (trigger) - 触发器
- ... (...) - 自定义数据

这是对base.event_register方法的封装，你可以在这里看到详细说明。

local trigger = player:event('玩家-选择英雄', function (trigger, player, name)
    -- 你的代码
end)

event_dispatch

触发事件

参数
- name (string) - 事件名
- ... (...) - 自定义数据

这是对base.event_dispatch方法的封装，你可以在这里看到详细说明。

player:event_dispatch('自定义事件', ...)

event_notify

触发事件

参数
- name (string) - 事件名
- ... (...) - 自定义数据

这是对base.event_notify方法的封装，你可以在这里看到详细说明。

player:event_notify('自定义事件', ...)

game_state

获取游戏状态

返回
- state (string) - 会是以下值中的一个
  - none - 空位
  - online - 在线
  - offline - 离线

local state = player:game_state()

get

获取属性

参数
- state (string) - 属性名称
返回
- value (number/string) - 数值或字符串

玩家属性说明见这里

local value = player:get '金钱'

get_hero

获取英雄

返回
- hero (unit) - 玩家的英雄

如果玩家没有英雄，则返回nil。

local hero = player:get_hero()

get_slot_id

获取玩家ID

返回
- id (integer) - 玩家ID

local id = player:get_slot_id()

get_team_id

获取队伍ID

返回
- id (integer) - 队伍ID

local id = player:get_team_id()

input_mouse

获取鼠标位置

返回
- mouse (point) - 鼠标位置

这个属性是由客户端上传的，需要客户端支持鼠标才有意义。

local point = player:input_mouse()

input_rocker

获取摇杆方向

返回
- rocker (number) - 摇杆方向

这个属性是由客户端上传的，需要客户端支持摇杆才有意义。如果摇杆是松开状态，则返回nil。

local rocker = player:input_rocker()

is_abort

是否放弃游戏

返回
- result (boolean) - 结果

放弃游戏的玩家无法再重连回游戏。

local result = player:is_abort()

kick

踢出游戏

参数
- backend (string) - 服务器记录的原因
- frontend (string) - 客户端显示的原因

player:kick('挂机', '你由于离开时间过长而被踢出游戏')

leave_reason

获取退出原因

返回
- leave_reason (string) - 原因

local reason = player:leave_reason()

lightning

创建闪电

参数
- data (table) - 属性表
返回
- lightning (lightning) - 闪电

闪电的属性与相关信息见[这里][lightning]

local lightning = player:lightning
{
    model = '闪电名称',
    source = {unit, 'socket_hit'},
    target = {point, 100},
}

lock_camera

锁定镜头

锁定镜头后，玩家无法通过客户端操作改变镜头状态，set_camera无效。使用unlock_camera解锁镜头。

player:lock_camera()

lock_camera_by_mouse_wheel

锁定滚轮改变镜头

锁定镜头后，玩家无法通过鼠标滚轮改变镜头状态,手机上禁用双指改变镜头。使用[unlock_camera_by_mouse_wheel]解锁滚轮。

player:lock_camera_by_mouse_wheel()

message

发送消息

参数
- data (table) - 属性表，可用属性如下：
  - text (string) - 消息内容
  - type (string) - 消息类型
    - ann 公告
    - chat 聊天
    - error 错误
  - time (integer) - 持续时间（毫秒）
  - sound (string) - 音效
  - effect (string) - 特效

player:message
{
    text = '消息内容',
    type = 'chat',
}

消息内容可以通过特殊标志进行格式化：

$player[x]$ 格式化为玩家[X]的名字。
&[X][Y]& 格式化为单位[Y]的头像，边框颜色为[X]。

player:message
{
    text = '$player1$选择了英雄&#0000ffAAA&',
    type = 'ann',
}

message_box

弹框消息

参数
- text (string) - 消息内容

player:message_box('消息内容')

play_music

播放音乐

参数
- name (string) - 音效名（音效表SoundData.ini里填的那个）

player:play_music(path)

play_sound

播放音效。这个api的音效现在是队列而不是打断，感觉有点问题，待之后一起改了

参数
- name (string) - 音效名（音效表SoundData.ini里填的那个）

player:play_sound(name)

set

设置属性

参数
- state (string) - 属性名称
- value (number/string/table)

玩家属性说明见这里

玩家属性涉及到底层同步，属性值大小存在上限，当序列化后的属性大小超过 1300 * 256 - 50 时会抛出异常提示大小受限, 所以不要一次性设置过大的表属性

player:set('金钱', 100)

set_afk

设置为挂机

player:set_afk()

set_camera

设置镜头

参数
- data (table) - 镜头状态
  - position (point/table) - 镜头目标位置，可以直接使用point，也可以使用{x, y, z}来表示一个三维的位置。
  - rotation (table) - 镜头旋转，使用{rx, ry, rz}来表示镜头在3个坐标轴上的旋转，默认为{0, 0, 0}。
  - focus_distance (number) - 摄像机与镜头目标之间的距离，默认为0。
  - time (integer) - 变换时间，默认为0，单位为毫秒。

当变换时间为0时会镜头立即变换到新的状态，否则镜头会在变换时间内平滑运动至新的状态。使用该方法会立即中断上次的镜头变换。

player:set_camera
{
    position = {x, y, z},
    rotation = {rx, ry, rz},
    focus_distance = 1000,
    time = 2000,
}

set_hero

设置英雄

参数
- hero (unit) - 玩家的英雄

player:set_hero(hero)

set_team_id

设置队伍ID

参数
- id (integer) - 队伍ID

player:set_team_id(1)

shake_camera

屏幕震动

参数
- type (integer) - 震动类型

目前支持的震动类型为0，1，2，3。

player:shake_camera(0)

unlock_camera

解锁镜头

player:unlock_camera()

unlock_camera_by_mouse_wheel

解锁滚轮改变镜头

player:unlock_camera_by_mouse_wheel()

user_agent

用户客户端

返回
- agent (string) - 客户端

用于分辨用户使用的客户端，该值由客户端上传。

local agent = player:user_agent()

user_id

虚拟的用户ID。其实我觉得这个用户ID没啥用，除了能保证每个人唯一且比较小。真实的user_id要用base.auxiliary.get_player_id

返回
- id (integer) - 用户ID

local id = player:user_id()

user_info

用户信息

参数
- type (string) - 类型
返回
- list (table) - 信息列表

类型为英雄时，返回用户可用英雄的名单；类型免费英雄时，返回用户免费英雄的名单；类型为养成时，返回用户使用的符卡名单。

local list = player:user_info '免费英雄'

user_level

用户等级

返回
- level (integer) - 平台等级

local level = player:user_level()

get_user_name

用户名字

返回
- user_name (string) - 用户名字

local user_name = player:get_user_name()

get_nick_name

用户昵称

返回
- nick_name (string) - 用户名字

local nick_name = player:get_nick_name()

get_user_info

获取玩家自定义属性

参数
- key (string) 在config.ini里写的user_info

返回
- string/int 属性值

local value = player:get_user_info(key)

camera_focus

摄像机跟随单位

参数
- unit 跟随的单位
返回
- 是否成功

player:camera_focus(unit)

get_scene_name

获取玩家的场景

返回
- scene_name (string) - 玩家所在场景

local scene_name = player:get_scene_name()

jump_scene

玩家跳转场景，如果目标场景不存在，将返回false

参数
- scene_name (string) - 玩家将要跳转的场景
- keep_hero (bool/false) - 是否带上主控单位，如果为true，主控单位会一起切换场景，否则主控单位留在原场景的同时，失去主控单位资格
返回
- result - 跳转成功与否

player:jump_scene()

获取​

add​

controller​

create_item​

create_unit​

each_player​

event​

event_dispatch​

event_notify​

game_state​

get​

get_hero​

get_slot_id​

get_team_id​

input_mouse​

input_rocker​

is_abort​

kick​

leave_reason​

lightning​

lock_camera​

lock_camera_by_mouse_wheel​

message​

message_box​

play_music​

play_sound​

set​

set_afk​

set_camera​

set_hero​

set_team_id​

shake_camera​

unlock_camera​

unlock_camera_by_mouse_wheel​

user_agent​

user_id​

user_info​

user_level​

get_user_name​

get_nick_name​

get_user_info​

camera_focus​

get_scene_name​

jump_scene​

获取

add

controller

create_item

create_unit

each_player

event

event_dispatch

event_notify

game_state

get

get_hero

get_slot_id

get_team_id

input_mouse

input_rocker

is_abort

kick

leave_reason

lightning

lock_camera

lock_camera_by_mouse_wheel

message

message_box

play_music

play_sound

set

set_afk

set_camera

set_hero

set_team_id

shake_camera

unlock_camera

unlock_camera_by_mouse_wheel

user_agent

user_id

user_info

user_level

get_user_name

get_nick_name

get_user_info

camera_focus

get_scene_name

jump_scene